package com.linkgie.galaxyframework.context;

import java.io.File;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 将一个接口方法标记为系统的主目录路径；
 * <p>
 * 
 * 要求被标记的方法没有参数，且返回值类型是 {@link String}、 {@link File}、之一；
 * <p>
 * 
 * 如果返回值类型是 {@link Storage} ，则路径类型 {@link #type()} 最终的确定值必须为
 * {@link HomePathType#DIR} ；
 * 
 * @author Hike
 *
 */
@Target({ ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
public @interface HomePath {

	/**
	 * 主目录路径；
	 * <p>
	 * 此属性可接收一组子路径，按顺序组合为完整的路径；
	 * <p>
	 * 
	 * 可以设置为目录路径，也可以设置为文件路径；
	 * 
	 * 必须是相对路径；<br>
	 * 
	 * 设置绝对路径将会引发系统异常 {@link IllegalArgumentException}；
	 * 
	 * @return
	 */
	String[] value();

	/**
	 * 路径的类型；
	 * <p>
	 * 
	 * 默认为 {@link HomePathType#UNDEFINED}；<br>
	 * 此时，如果定义了默认资源 {@link #defaultResource()}，则等同于声明为 {@link HomePathType#FILE};
	 * <br>
	 * 
	 * <p>
	 * 
	 * 当路径不存在时，
	 * <p>
	 * 如果路径的类型 {@link HomePathType#DIR} ，则将创建相应的目录；
	 * <p>
	 * 如果路径的类型 {@link HomePathType#FILE} ，则将创建相应的文件，<br>
	 * 此时如果定义了 {@link #defaultResource()} ，则以默认资源初始化文件，否则创建空文件 ；
	 * <p>
	 * 如果路径的类型 {@link HomePathType#UNDEFINED} ，则不做处理；
	 * <p>
	 * 
	 * @return
	 */
	HomePathType type() default HomePathType.UNDEFINED;

	/**
	 * 默认资源的路径；
	 * <p>
	 * 可选设置；
	 * <p>
	 * 如果定义一个默认资源，则此当声明目录路径不存在时，以默认资源的内容将该目录路径初始化为文件；<br>
	 * 通过此特性可以方便默认配置文件的生成；
	 * <p>
	 * 
	 * 如果资源路径是绝对路径（即以 "/" 开头），则从声明 HomePath 方法的接口的类路径根目录下搜索； <br>
	 * 如果资源路径是相对路径，则从声明 HomePath 方法的接口的包的类路径目录下搜索；
	 * <p>
	 * 
	 * 具体实现的搜索规则遵照 {@link Class#getResourceAsStream(String)} 定义的规则；
	 * 
	 * @return
	 */
	String defaultResource() default "";

	/**
	 * 目录路径对应的系统属性；
	 * <p>
	 * 可选设置；
	 * <p>
	 * 如果设置了系统属性，则将此目录的路径值对应地设置到系统属性；
	 * 
	 * @return
	 */
	String[] systemProperties() default {};
}
